Skip to main content

使用会话认证添加认证

会话认证结合了基本认证的元素——Zapier 请求用户名和密码，以及 OAuth v2 的元素——Zapier 将用户重定向到应用的网站以授权访问。用户凭证会被交换为一个令牌，用于后续的 API 调用。

这类似于浏览器中的基于 cookie 的认证，只是这里的“cookie”是一个由 Zapier 存储的认证令牌。

使用会话认证添加认证

如果您的 API 设计用于基于会话、cookie 或令牌的认证，请在 Zapier 集成中使用会话认证。

1. 构建输入表单​

  • 在 Zapier 视觉构建器中打开认证选项卡，然后选择会话认证。

使用会话认证添加认证

  • 会话认证不包含任何默认输入字段。通过选择“添加字段”来添加 API 所需的字段，并为每个字段填写详细信息。请先添加最常用的字段，按照用户预期的顺序添加，因为添加后无法重新排序字段。

  • 构建会话 输入表单 时，有两种类型的字段可用。标准字段的工作方式类似于 Zapier 中的其他表单字段，用于 输入表单 中的触发器和操作。计算字段 确保您的应用认证 API 调用响应中返回特定字段。

  • 对于每个字段，添加所需的 Key，即您的 API 用于引用此字段的名称。

  • 根据需要填写可选字段，尤其是 Label：

– Label：此字段的人性化名称，将显示在认证表单中供用户查看。

– Required?（复选框）：如果此字段是认证成功所需的，则选中。

– Type：所有输入字段默认使用 string 文本字段；如果您希望在用户输入时隐藏数据，请选择 password。

– Help Text：提供详细信息以帮助用户进行认证，尤其是如果他们不确定在哪里找到应用中的所需数据。请使用 Markdown 格式化文本，并根据需要添加超链接。

– Input Format：（可选）帮助用户明确需要输入的具体数据。例如，对于 子域名，如 https://.yourdomain.com/。

– Default Value：为该字段提供一个备用值。对于可选字段，此值将在初始连接创建时设置，并在每次 Zap 运行时用于 API 调用中，以替换缺失或空值。对于必填字段，此值仅在连接创建时使用，而在 Zap 运行时如果值为缺失或空值，Zapier 会引发错误。

  • 标记为密码的输入字段，以及所有包含敏感私有数据的认证字段（如会话认证中的用户名和密码），都会在运行时自动屏蔽。这些值存储在 Auth bundle 中并用于 API 调用，但在 Zapier 的日志中会被替换为屏蔽值，例如 :censored:6:82a3be9927:。因此，无法在 Zapier 的日志中查看确切的令牌或密钥。要验证认证返回的令牌是否与后续 API 调用中使用的一致，您可以比较屏蔽值的字符，例如 :censored:6:82a3be9927: 在后续调用中会以相同的结尾如 9927。

  • 每个输入字段都会在您的认证设置中列出其标签、键、类型和必填状态。点击字段以编辑它，或点击齿轮图标并选择删除来移除字段。

  • 对于仅在 OAuth v2 和会话认证中可用的计算字段，请查看 计算字段文档。

2. 添加令牌交换请求​

  • 添加令牌交换请求 URL 并选择 HTTP 方法。Zapier 会自动将输入字段中的数据包含在 API 请求正文中。如果您的 API 期望将数据放在 URL 参数或 HTTP 标头中，或者需要额外数据，请点击“显示选项”并添加 API 调用所需的详细信息。通常不推荐在 URL 参数中传递任何敏感信息（如密码），最好通过标头或正文传递。

使用会话认证添加认证

  • 要自定义令牌交换请求，请选择“切换到代码模式”并编写自定义 JavaScript 代码来处理 API 调用和响应解析。您第一次点击切换时，Zapier 会 将您的 API 调用转换为代码。但是，如果您切换回表单模式，Zapier 不会将您的代码更改转换回表单模式，也不会将后续表单更改添加到您的代码中。

  • 如果您的令牌交换请求未在顶层返回令牌和/或任何 计算字段，请使用 代码模式 修改响应，使这些字段在顶层可用。不可能从响应中存储带有嵌套键的对象。

  • 所有值将通过 \{\{bundle.authData.field\}\} 引用，其中 field 是响应中的键。

3. 添加测试 API 请求​

  • 添加一个不需要任何配置的 API 调用，通常是 /user 或 /me 调用。添加 API 调用的 URL，并设置调用类型，通常为 GET。这将测试用户输入的凭证是否能启用对您的应用的成功 API 调用。

  • 会话认证没有定义后续 API 调用中如何包含访问令牌的标准，因此与其他认证方法不同，Zapier 默认不会包含访问令牌。您需要在测试请求中添加它，并在后续的触发器和操作步骤的 API 调用中添加它。

  • 点击“显示选项”，然后根据需要将访问令牌添加到 API 调用的 URL 参数或 HTTP 标头中。通常不推荐在 URL 参数中传递任何敏感信息（如密码），最好通过标头或正文传递。访问令牌位于 bundle.authData 中，通常引用为 \{\{bundle.authData.access_token\}\}、\{\{bundle.authData.sessionToken\}\} 或类似字段，具体取决于您的令牌交换响应如何包含令牌。

使用会话认证添加认证

4. 配置连接标签​

查看 连接标签文档 以可选方式区分用户连接的应用账户。

5. 测试您的认证​

使用有效用户账户进行连接以 测试认证。

需要帮助？告诉我们您的问题，我们会将您连接到合适的资源或联系支持。